Almathera Ten Pack 3: CDPD 3/Almathera Ten on Ten - Disc 3: CDPD3.iso/fish/751-760/752/toolmanager/goodies/upd1_20.lha/upd/Upd.Doc

Text File | 1992-08-05 | 14KB | 388 lines

Release 1.20

        The minimal player daemon - upd
        ===============================

    © 1991 Jonas Petersson & Absolut Software (aka Sirius Soft)



Introduction:
=============

Wouldn't it be nice to have a process hanging around to play any
sound file for you on demand instead of you having to do all this
mucking about with audio.device etc? But it really has to be small
and it HAS to be able to play my very large samples anytime...
I must be able to call it simply from anywhere - even from scripts!

Tricky, but it can be done.

As a feature you can register you favourite sounds in a configuration
file and well behaved programs will use the ones you like right now.
It also has Arexx support - to be truely honest, that the ONLY way to
use it... As of 1.01, there is also a fade option.

Actually, "minimal" is not quite true anymore as speech is available
starting 1.20... As a spin-off of this you also get a "say" program
that can play phonemes.

Current version works rather well along the way I intended.


Usage:
======
**** Note: rehacked interface

    [run] upd [-bBUFSIZE] [-fIDFILE] [-pPRIORITY]

The "run" is of course optional, but daemons really should be in the
background unless you want the see the debugging information.  "bufsize"
is the amount of chip memory that each of the four buffers will use
while playing.  (These are allocated at start to make sure you will be
able to play anytime - as long as you can get hold of the audio
channels...).  Default is 1024 and specifying less than 64 will give you
the default. (I've heard that some people can't ever get anything good
out with less than a 1K buffer - am I really the only one with a quick
enough HD/SCSI interface?)

NOTE: Don't make the buffer bigger than you actually need - a large
buffer also means that the sample will start a little bit later since
more information must be loaded before it can begin!

If the IDfile parameter exists, it will be used instead of the
default s:upd.IDs.

As of 1.20 I've also added the priority option to satisfy some requests
from people who prefer their sound to be perfect before getting things
done... You people may specify -p35 or something like that along with
some huge buffer. Of course, you can also lower priority with this option.

The above won't produce any sound as you probably realise.  Once run, the
only way to talk to upd is with Arexx - I even removed the BREAK stuff
that was in it for Zound, since Arexx could hang around waiting for a
reply forever when you interupted the sound that way. The break will
"wait" until the daemon is idle next time.

upd currently knows of these commands:

    file filepath [options] [anotherfilepath [options]]
    id   id-in-s:upd.IDs
        rescan new-id-file
    fade #-of-steps-per-bufsize
    say string-to-translate-and-say
    phoneme phoneme-string-to-say
    exit

The 'fade' command is new to 1.01 and might need some explanation:
What is does is merely reconfigure upd for future requests. By default
fade is set to 0 which means that any playing sound will be cut off
as soon as a new AREXX command arrives. Any other number indicates that
when a new request arrives, first fade out the current sound by lowering
the volume by the specified amount by each played buffer until volume reaches
zero. As the observant reader realises, a value exceeding 64 will do
the same thing as 0 and a negative value may give nondesired effects...

'say' and 'phoneme' are new as of 1.20 and their use should be obvious.
These are really just a spin-off from what was added to the ID file.
Speech currently won't fade - I fail to see the beauty in fading it...

Well, there is actually one more command: 'Can it, Marvin'. This will
silently interrupt the current sample. (To be truely honest, ANY command
will interrupt a sample - if it's known, it will be used, otherwise the
sound just stops). Be careful with the 'rescan' command: if there is a
problem reading the new file, you will have no IDs at all...

The options are the same as for Zound except for the -n option that doesn't
exist here (tell me you need it and I'll fix that too... sigh). Here's the
list:

    -r rate    How fast to play the sample. Default is what is in the
        8SVX header or 310 if it's a raw file. This is usually
        reasonable - most 'raw' samples I've come across are either
        310 or 155. Lower numbers will play the sample faster.

    -v volume    Ranges between 0 and 64, 64 being max and default.

    -s start    Possible offset from the beginning. Default 0.

    -l length    Possible length unless you want it all. Default is
        length of the sample. Be careful with these two, or
        you might get undesired results.

    -c cycles    How many times to play each buffer. Default 1. Not
        very useful, but you can get a nice "mouse" effect by
        setting this to 2 and playing twice as fast...

    -d        Show debug information. Note that this will appear on
        the standard output of the DAEMON, not where you called
        it from (that is, the ARexx script or wherever).

    -L        Play the sample in the left speaker only. If it's a stereo
        sample only the left channel samples are used.
    -R        Same as '-L' but for right speaker.
    -S        Play in both speakers even if it's a mono sample.
        Default for these three options are of course what is in the
        8SVX header or -L if it's a raw sample.

Examples:
=========

* Example of usage (from WShell etc):

    "address play file 'sounds:chopper'
    "address play fade 2
    "address play id 2001
        "address play rescan 'ram:upd.IDs'
    "address play exit


* If you are using the vanilla 2.0 AREXX you might have to create a file
  like this:

    /* A test script in AREXX */

    address PLAY say "Hi there!"

  Then execute it with 'rx filename.rexx'

  Alternatively, you can give a command like this (note the tick [']):

    rx 'address PLAY say "Hi there!"


* Say "emulations":

    address play say "-f -r -s100 E T phone home."
    address play phoneme "-s200 YUWNAEZ PEH1TERSUN"


NOTE: Arexx normally converts everything to UPPERCASE and might try to
do arithmetics etc on filenames which is why it's generally a good idea
to 'singelquote' all paths, IDs etc. If you're looking for the port
'the hard way' to send your own message, the name is "PLAY" in uppercase.

NOTE2: If you are REALLY in a hurry to get rid of upd you could do this:
 1) Send a any dummy Arexx message (this will stop the sound)
 2) Send a break C to upd - break still works when upd is idle.
or
 A) Send the exit message.

The last might sound much easier than the first unless you (like me)
have a trapped DisplayBeep() that 'pings' via upd.  In this case,
producing a DisplayBeep() and a break C is much simpler.  The order is
not relevant since the break is "queued".


Hints:
======

Running upd from your SOUNDS: directory is a nice way to get rid of having
you type the FULL path everytime you want to play a sample. (The daemon
has no simple way of knowing WHERE you were when you sent the message
(that I know of) and therefore assumes it to be in the current directory)


Files:
======

    s:upd.IDs

This file contains the IDs of your favourite samples like a database
the is easily editable. File format:


# Lines starting with '#' are comments
# Id list for micro player daemon
# Created 910201 Jonas Petersson ([e-mail])
# These sounds could be called for at certain situations
# On severe error
BUG    sounds:explosion -S
# When asked for confirmation
CONFIRM sounds:PressLeftMouseButton -L
# Minor trouble
ERROR   sounds:ImSorryDaveImAfraidICantDoThat -R
# Going down...
GURU    sounds:RoysDeathMonologueFromBladerunner -S
# Personal shortcuts/favourites
2001    sounds:openpod -L sounds:hal -R
# These should always work:
ET      -SAY -r -f -p100 -F20000 -s110 E T phone home.
AUTHOR  -PHONEME YUWNAEZ PEH1TERSUN
# These are for Arq
warn_write_protected    -SAY I'm afraid I can't do that.
warn_insert_volume      -SAY I can't see it.
warn_delete             -SAY Oh no.
warn_printer            -SAY Printer trouble.
error_task_held         -SAY You are in deep shit.
error_read_write        -SAY Bad disk.
error_general           -SAY Error.
warn_general            -SAY Warning.
query_general           -SAY Please.
beep                    -SAY Beep.


-SAY and -PHONEME are special "files" as of 1.20. These instead trigger
the use of translator/narrator since some people don't have a lot of
samples around. Remember that everything is defferent here - options
come BEFORE the string and have other meanings than for samples. I've
tried to keep the the same as the command 'say' uses:

    -m/-f    Male/Female
    -n/-r    Natural/Robot
    -p###    Pitch
    -v###    Volume
    -s###    Speed (rate really)
    -F###    Sample frequency

    (Defaults are the same as for "say")

Removing entries will of course result in no sound (upd might mourn about
it on the standard output though, unless you redirect it). Remember that
ARexx might convert to uppercase unless you quote!

Feel free to add whatever you like. Could be nice with some standard though.
If you make a program that uses several ID's it would be a good idea to have
the same prefix for instance.

Suggestions are welcome. Mjl's Arq is an example of a program that uses
this feature. Read Arq's docs for details.

NOTE: It *IS* possible to have white space, lowercase etc in the IDs, but
it might cause confusion if used. Be warned.

NOTE2: The file is scanned once when the program starts. If you make any
changes to it, you'll have to restart the deamon.


Return codes:
=============

If the Arexx command returns 20, the secondary result code gives the
reason for the failure:

10    Can't allocate channels.
17    Can't open s:upd.IDs on request to play by ID.
18    Requested ID not found.
19    Trouble reading new ID file.
20    Error during parse of options.
21    Can't open file with sample.
22    File is IFF, but not FORM 8SVX.
23    Bad IFF file.
24    Bad CHAN length.
25    Bad VHDR length.
26    Can't open file 2nd time. (For stereo possibility)
30    Can't play backwards. (Weird options)
31    Can't allocate IOAudio structs.
32    Can't open ports for channels.
47    Can't open the translator library.
48    Translator won't use that string.
50    Bad options to -SAY/-PHONEME in ID line.
51    Can't open the narrator device.
52    Couldn't Allocate talk Signal bit.
53    Narrator won't do that. Usually bad pitch etc.



Being interrupted to do something else is not considered a failure. Note
that this is true even if the current message has not been parsed yet.
That is if UPD is sent these two messages (in order):

    address PLAY phoneme "Hi there!"
    address PLAY say "Hi there!"

It will not parse the first one since it knows there is another one
waiting and therefore returns 0 (OK) for the first even though it
contains invalid phonemes. This should hardly be a problem and you
hardly want it to work the other way since that might slow down things
significantly when you have a lot of queued requests (likely when trapping
DisplayBeep() for instance). [Note that putting the above two messages
after each other in a script WONT send them at the same time since upd
doesn't release the first message until it's done!]


Future enhancements:
====================

Maybe automatic detach (didn't work well in Aztec 5.0a, and I havn't really
tried with 5.0d yet).

Probably not very much else - this is a simple sound daemon for minor
background purposes of helping simple programs do more than DisplayBeep().
I'd like to think of it as a complement to SPEAK: - if you want more
you probably want it interactive. (Hmm, that's a thought - a SOUND: device)



Problem history:
================

1. If your sample is on a floppy (or a very slow HD) there might be
   some sounds of silence when the playing rate exceeds the loading
   rate...
Fix: You can now specify the amount of memory to be used by upd when you
   start the daemon as in: 'upd -b2000'. But note that a larger buffer also
   makes a longer delay until you hear the first part of the sound - it
   doesn't start until it has filled the first buffer.

2. Stereo and Fibonachi packed samples not yet supported (there are loading
   problems - play them with 'Zound' instead for now).
Fix: Stereo is OK now if you use the above size option (it actually worked
   in RAM: before too - but I didn't enable it for the prerelease). As for
   Fibonachi: it's not too hard to fix, but I've never seen anyone using it -
   is it worth the effort? If you happen to have a Fib-sample - PLEASE send it
   to me - I don't have the patience to reconstruct one by hand...

3. Could hang forever if someone stole the channel.
Fix: So, I didn't check everything in 0.99 - now I do (I hope... ;-)

4. -s and -l weren't used in 0.99, now they are.

5. On request from the UK CDTV developers, FADE was added as of 1.01

6. On request from various people, added option -p## at startup to make
it simpler to raise priority for those demanding perfect sound but are
to lazy to use "ChangeTaskPri" for it...

7. Added speech and better command line parsing as of 1.20.

Thanks to [e-mail] for the idea.


Distribution
============

  UPD is not public domain. A friend of mine advised me to call it
"Freely Distributable Copyrighted" instead. That's close enough.
If You wish to include it with a commercial program feel free provided
that You send me a registered copy. And don't forget to mention me
in the manual.

  As always, Fred Fish is free to include it in his library.

  Source code? You mean there is something to IMPROVE??? Right, send
me a message then and I'll think about it...





    Jonas 'Zaphod' Petersson
    Albrektsvagen 113A
    S-603 53  Norrkoping
    SWEDEN
    Phone: [phone]    (After four rings magrathea will let you leave
                 a message for me if you log in as "guest".)

    [e-mail]                   /* At home */
    [e-mail]                    /* At work  - Quickest */


Feel free to send comments, bug reports (huh?), money, coke, beer...
[Sorry, girls are no longer allowed as I'm married now!]

Just a "Hi, I liked your program" is as good as a few bucks - I wrote this
because I needed it, not to make money out of it...